feat: Introduce separate replica version by frankdavid · Pull Request #11401 · dfinity/ic

frankdavid · 2026-09-01T15:15:25Z

There used to be a single version: the one under /opt/ic/share/version.txt, read by the orchestrator and passed to the replica. During fast GuestOS upgrade, the replica binaries are hot-swapped via an overlay while the node keeps running the old GuestOS. The base GuestOS version and the replica version must be distinguished.

PlatformVersion (new struct in ic-types, next to ReplicaVersion) holds both guestos_version (the GuestOS the node booted from) and replica_version (the running replica binary). replica_version: ReplicaVersion in ReplicaConfig is replaced by platform_version: PlatformVersion.
Build: the GuestOS image now ships a second version artifact, /opt/ic/share/replica_version.txt (plus its -test variant). During a fast upgrade, the sysext overlay will shadow it with the post-upgrade version, while version.txt — now explicitly the GuestOS version — is never shadowed.
Orchestrator: reads both files (--replica-version-file → replica version, --guestos-version-file → GuestOS version) and passes them when starting the replica process.
Observability: /api/v2/status gains an optional guestos_version field alongside impl_version.
Metrics: custom-metrics.sh now also exports a replica_version metric.

There used to be a single version: the one under `/opt/ic/share/version.txt`, read by the orchestrator and passed to the replica. During fast GuestOS upgrade, the replica binaries are hot-swapped via an overlay while the node keeps running the old GuestOS. The base GuestOS version and the replica version must be distinguished. - **`PlatformVersion`** (new struct in `ic-types`, next to `ReplicaVersion`) holds both `guestos_version` (the GuestOS the node booted from) and `replica_version` (the running replica binary). `replica_version: ReplicaVersion` in ``ReplicaConfig` is replaced by `platform_version: PlatformVersion`. - **Build**: the GuestOS image now ships a second version artifact, `/opt/ic/share/binary_version.txt` (plus its `-test` variant). During a fast upgrade, the sysext overlay will shadow it with the post-upgrade version, while `version.txt` — now explicitly the GuestOS version — is never shadowed. - **Orchestrator**: reads both files (`--version-file` → binary version, `--guestos-version-file` → GuestOS version) and passes them when starting the replica process. - **Observability**: `/api/v2/status` gains an optional `guestos_version` field alongside `impl_version`. - **Metrics**: `custom-metrics.sh` now also exports a binary_version metric.

zeropath-ai · 2026-09-01T15:16:07Z

✅ No security or compliance issues detected. Reviewed everything up to 5e4e48e.

Security Overview

🔎 Scanned files: 52 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/f5e9d2bb-29a4-4b64-902a-391d65fd8b2d?scanId=e0dfdbf5-bfe6-4193-ae56-7438f6478c26&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► ic-os/components/guestos/ic-replica.service ExecStart argument changes for replica/guestos versioning ► ic-os/components/monitoring/guestos/custom-metrics.sh Add replica_version metric and read replica version file ► ic-os/components/monitoring/metrics-proxy/guestos/metrics-proxy.yaml Keep replica_version metric in proxies ► rs/boundary_node/ic_boundary/src/http/handlers.rs Include guestos_version in status response ► rs/consensus/dkg/src/dkg_key_manager.rs Use platform_version instead of replica_version in tests and config ► rs/consensus/dkg/src/lib.rs Extract platform_version from ReplicaConfig and preserve replica_version via platform_version field ► rs/consensus/dkg/src/payload_validator.rs Adjust tests to use platform_version in replica config ► rs/consensus/mocks/src/lib.rs Update mock to include PlatformVersion and adjust replica_version handling ► rs/consensus/src/consensus/batch_delivery.rs Use platform_version in replica config for tests ► rs/consensus/src/consensus/block_maker.rs Pass replica_version() from config instead of direct replica_version ► rs/consensus/src/consensus/catchup_package_maker.rs Use replica_version() from config in package creation ► rs/consensus/src/consensus/finalizer.rs Switch to replica_version() for finalization metadata ► rs/consensus/src/consensus/malicious_consensus.rs Use replica_version() from config in content creation ► rs/consensus/src/consensus/notary.rs Use replica_version() from config for notarization content ► rs/consensus/src/consensus/random_beacon_maker.rs Use replica_version() from config for beacon content ► rs/consensus/src/consensus/random_tape_maker.rs Use replica_version() from config for random tape content ► rs/consensus/src/consensus/share_aggregator.rs Use platform_version in tests instead of replica_version in several places ► rs/consensus/src/consensus/validator.rs Use replica_version() from config for validation checks ► rs/consensus/tests/framework/types.rs Pass replica_version() instead of direct replica_version in consensus setup ► rs/consensus/tests/payload.rs Update types to include PlatformVersion and adjust replica_config construction ► rs/http_endpoints/public/src/dashboard.rs\n Switch to PlatformVersion and display replica_version via platform_version ► rs/http_endpoints/public/src/lib.rs Update public endpoints to use PlatformVersion in routing/config ► rs/http_endpoints/public/src/status.rs Update status to expose PlatformVersion and guestos_version ► rs/http_endpoints/public/templates/dashboard.html Display replica_version via platform_version and add GuestOS Version ► rs/http_endpoints/public/tests/common/mod.rs Update test imports to use test_platform_version instead of test_replica_version ► rs/determinism_test/src/setup.rs Update replica_config to use platform_version in setup ► rs/consensus/tests/framework/test_runner.rs Update test data generation to use test_platform_version ► rs/consensus/tests/payload.rs Adjust consensus payload tests to incorporate PlatformVersion ► rs/http_endpoints/public/src/status.rs Replace replica_version references with platform_version in status responses ► rs/http_endpoints/public/src/dashboard.rs Adjust dashboard data model to include PlatformVersion andGuestOS fields ► rs/http_endpoints/public/src/dashboard.rs Update dashboard HTML to show GuestOS Version and PlatformVersion fields

zeropath-ai · 2026-09-01T15:16:29Z

✅ No security or compliance issues detected. Reviewed everything up to 5e4e48e.

Security Overview

🔎 Scanned files: 52 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/6992424c-495e-4621-b441-efd6821a4be6?scanId=aa54cdc1-c0a8-4804-a7d4-d8e2dc08c993&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► ic-os/components/guestos/ic-replica.service Update ExecStart and add replica/version file references to replica_version.txt and version.txt ► ic-os/components/monitoring/guestos/custom-metrics.sh Add replica_version metric and read from replica_version.txt ► ic-os/components/monitoring/metrics-proxy/guestos/metrics-proxy.yaml Keep replica_version metric for replica/version tracking ► ic-os/defs.bzl Introduce copy_replica_version_txt and test_replica_version_txt rules for replica_version.txt ► rs/boundary_node/ic_boundary/src/http/handlers.rs Add guestos_version field in status response ► rs/consensus/dkg/src/dkg_key_manager.rs Update tests to use test_platform_version instead of test_replica_version for platform/version handling ► rs/consensus/dkg/src/lib.rs Refactor DkgImpl to set node_id/subnet_id with updated replica_version handling via replica_config.replica_version() ► rs/consensus/mocks/src/lib.rs Use PlatformVersion and adjust replica_version handling to replica_version() in mocks ► rs/consensus/src/consensus/batch_delivery.rs Update tests to use test_platform_version for platform_version instead of test_replica_version ► rs/consensus/src/consensus/block_maker.rs Use replica_version() from replica_config where referenced ► rs/consensus/src/consensus/catchup_package_maker.rs Use replica_version() from replica_config in package creation ► rs/consensus/src/consensus/finalizer.rs Use replica_version() from replica_config in finalization logic ► rs/consensus/src/consensus/malicious_consensus.rs Use replica_version() from replica_config in content creation ► rs/consensus/src/consensus/notary.rs Use replica_version() from replica_config in notary and notarization content ► rs/consensus/src/consensus/random_beacon_maker.rs Use replica_version() from replica_config in beacon content ► rs/consensus/src/consensus/random_tape_maker.rs Use replica_version() from replica_config in random tape content ► rs/consensus/src/consensus/share_aggregator.rs Use replica_version() from replica_config in tests and configurations ► rs/consensus/src/consensus/validator.rs Replace replica_version reference with replica_version() from replica_config in validation logic ► rs/consensus/tests/framework/types.rs Use replica_version() from replica_config in consensus dependencies ► rs/consensus/tests/payload.rs Update ReplicaConfig to include platform_version with guestos_version and replica_version fields ► rs/determinism_test/src/setup.rs Use platform_version (test_platform_version) instead of test_replica_version in replica_config ► rs/http_endpoints/public/src/dashboard.rs Dashboard displays platform_version and guestos_version instead of replica_version ► rs/http_endpoints/public/src/lib.rs Use PlatformVersion in public HTTP endpoints instead of ReplicaVersion ► rs/http_endpoints/public/src/status.rs Status endpoint uses PlatformVersion and guestos_version fields ► rs/http_endpoints/public/templates/dashboard.html Display platform_version.replica_version and platform_version.guestos_version ► rs/http_endpoints/public/tests/common/mod.rs Switch test imports from test_replica_version to test_platform_version ► rs/consensus/tests/framework/test_runner.rs Switch imports to test_platform_version for platform/version handling ► rs/http_endpoints/public/src/dashboard.rs Prefix changes reflect platform_version usage in dashboard wiring ► rs/consensus/tests/payload.rs Update payload tests to construct platform_version alongside replica_version in ReplicaConfig

Copilot

Pull request overview

Introduces separate GuestOS and replica binary version tracking for fast upgrades.

Changes:

Adds PlatformVersion and propagates it through replica and consensus.
Exposes GuestOS version through status APIs and metrics.
Packages separate GuestOS and binary version artifacts.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`rs/types/types/src/replica_version.rs`	Defines `PlatformVersion`.
`rs/types/types/src/replica_config.rs`	Uses platform version configuration.
`rs/types/types/src/messages/http/tests.rs`	Updates status fixtures.
`rs/types/types/src/messages/http.rs`	Adds GuestOS status field.
`rs/types/types/src/lib.rs`	Exports `PlatformVersion`.
`rs/types/types_test_utils/src/ids.rs`	Adds platform-version fixture.
`rs/replica/src/setup_ic_stack.rs`	Propagates platform versions.
`rs/replica/src/args.rs`	Adds GuestOS version argument.
`rs/replica/setup_ic_network/src/lib.rs`	Passes platform versions into consensus.
`rs/replica/bin/replica/main.rs`	Constructs runtime platform version.
`rs/replica_tests/src/lib.rs`	Updates replica test setup.
`rs/replay/src/validator.rs`	Updates replay configuration.
`rs/orchestrator/src/upgrade.rs`	Tracks both versions during upgrades.
`rs/orchestrator/src/processes.rs`	Passes both versions to replicas.
`rs/orchestrator/src/orchestrator.rs`	Loads both version files.
`rs/orchestrator/src/args.rs`	Adds GuestOS version-file argument.
`rs/https_outcalls/consensus/src/pool_manager.rs`	Uses binary version for artifacts.
`rs/http_endpoints/public/tests/common/mod.rs`	Updates endpoint test setup.
`rs/http_endpoints/public/src/status.rs`	Reports both versions.
`rs/http_endpoints/public/src/lib.rs`	Propagates platform versions.
`rs/determinism_test/src/setup.rs`	Updates determinism fixture.
`rs/consensus/tests/payload.rs`	Updates payload test configuration.
`rs/consensus/tests/framework/types.rs`	Uses nested replica version.
`rs/consensus/tests/framework/test_runner.rs`	Updates consensus fixtures.
`rs/consensus/src/consensus/validator.rs`	Validates binary versions.
`rs/consensus/src/consensus/share_aggregator.rs`	Updates test configuration.
`rs/consensus/src/consensus/random_tape_maker.rs`	Emits binary version.
`rs/consensus/src/consensus/random_beacon_maker.rs`	Emits binary version.
`rs/consensus/src/consensus/notary.rs`	Uses binary version.
`rs/consensus/src/consensus/malicious_consensus.rs`	Uses binary version.
`rs/consensus/src/consensus/finalizer.rs`	Uses binary version.
`rs/consensus/src/consensus/catchup_package_maker.rs`	Uses binary version.
`rs/consensus/src/consensus/block_maker.rs`	Uses binary version.
`rs/consensus/src/consensus/batch_delivery.rs`	Updates test configuration.
`rs/consensus/mocks/src/lib.rs`	Builds platform-version mocks.
`rs/consensus/dkg/src/payload_validator.rs`	Updates test configuration.
`rs/consensus/dkg/src/lib.rs`	Extracts binary version for DKG.
`rs/consensus/dkg/src/dkg_key_manager.rs`	Updates test configuration.
`rs/boundary_node/ic_boundary/src/http/handlers.rs`	Updates status response construction.
`ic-os/defs.bzl`	Packages binary version artifacts.
`ic-os/components/monitoring/guestos/custom-metrics.sh`	Adds binary-version metric.
`ic-os/components/guestos/ic-replica.service`	Supplies both version files.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

… versions PR #11401 replaced the single ReplicaVersion::set_default_version() call with a PlatformVersion (guestos_version + replica_version) reported via the ic_replica_info metric, to distinguish the two during fast GuestOS upgrades. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VnwZHP5Bm5AEaugi8a96Hu

frankdavid added 2 commits September 1, 2026 15:14

GuestOS version

0627e71

frankdavid requested review from a team as code owners September 1, 2026 15:15

github-actions Bot added the feat label Sep 1, 2026

Automatically fixing code for linting and formatting issues

cc6c2c2

github-actions Bot added @node @core-protocol labels Sep 1, 2026

frankdavid requested a balanced review from Copilot September 1, 2026 15:23

Copilot started reviewing on behalf of frankdavid September 1, 2026 15:23 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread ic-os/components/monitoring/guestos/custom-metrics.sh Outdated

Comment thread rs/http_endpoints/public/src/status.rs

Address copilot comments

d0fd2eb

frankdavid requested a review from a team as a code owner September 1, 2026 16:00

frankdavid requested a balanced review from Copilot September 1, 2026 16:00

github-actions Bot added the @dre label Sep 1, 2026

Copilot started reviewing on behalf of frankdavid September 1, 2026 16:00 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread rs/orchestrator/src/processes.rs

Comment thread rs/consensus/tests/framework/test_runner.rs Outdated

fmt

57c0c96

pierugo-dfinity reviewed Sep 2, 2026

View reviewed changes

Update rs/orchestrator/src/orchestrator.rs

2a70de9

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

Bownairo approved these changes Sep 2, 2026

View reviewed changes

frankdavid added 2 commits September 2, 2026 18:19

Address comments

e7f7086

Add guestos_version to UpgradeTestScenario

18d68d8

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

frankdavid and others added 4 commits September 3, 2026 13:38

Update rs/replica/bin/replica/main.rs

c3e13d4

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

Add platform_version to dashboard

3a96aac

replica_config.replica_version()

00d19ac

Use different test_replica_version and test_guestos_version

f8415eb

frankdavid added 5 commits September 3, 2026 14:09

Don't clone replica_version

89d8324

Don't clone replica_version 2

e5c7346

Remove clones

0baa1bc

Add ic_guestos_version to orchestrator_info

4c2fcc8

Make clippy happy with too_many_arguments in tests

8c0476c

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

Comment thread rs/http_endpoints/public/src/lib.rs Outdated

Comment thread rs/replay/src/validator.rs Outdated

Comment thread rs/orchestrator/src/orchestrator.rs Outdated

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

Comment thread ic-os/components/monitoring/guestos/custom-metrics.sh

frankdavid added 2 commits September 3, 2026 16:54

Pass guestos version to replay

5aa994b

Pass guestos version to BoundaryNodeManager

d9e0da2

pierugo-dfinity reviewed Sep 4, 2026

View reviewed changes

Comment thread rs/orchestrator/src/metrics.rs Outdated

Comment thread rs/replay/src/cmd.rs Outdated

Comment thread rs/types/types/src/replica_version.rs

frankdavid and others added 4 commits September 7, 2026 13:50

Update rs/replay/src/cmd.rs

c3a8bea

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

Add PlatformVersion to dashboard

c08d675

Update rs/orchestrator/src/metrics.rs

835637f

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

binary_version -> replica_version

5e4e48e

frankdavid requested a review from pierugo-dfinity September 7, 2026 14:13

pierugo-dfinity approved these changes Sep 7, 2026

View reviewed changes

NikolaMilosa approved these changes Sep 8, 2026

View reviewed changes

frankdavid added this pull request to the merge queue Sep 8, 2026

frankdavid removed this pull request from the merge queue due to a manual request Sep 8, 2026

frankdavid added this pull request to the merge queue Sep 8, 2026

Merged via the queue into master with commit 5a7458b Sep 8, 2026
46 checks passed

frankdavid deleted the frankdavid/include-guestos-version branch September 8, 2026 09:49

Uh oh!

Conversation

frankdavid commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeropath-ai Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeropath-ai Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

frankdavid commented Sep 1, 2026 •

edited

Loading

zeropath-ai Bot commented Sep 1, 2026 •

edited

Loading

zeropath-ai Bot commented Sep 1, 2026 •

edited

Loading